code repo connnect test

[shlib.git] / doc / design-doc / 3.3.catalog-tree structure data orgnize.txt

doc of shlib

  Copyright (C) 2022- Free Software Foundation, Inc.

  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved.

The following contributions warranted legal paper exchanges with the
Free Software Foundation.


[tmp]
@ trimple name string.
# use attr/attr-var instead of var, because it will mix with the variable in src code.
# use node-type instead of type. use file-type instead of type.


# guide-catalog
===============
 1. introduction
 2. example
 3. concept
 4. attr-var
 5. operation
 6. node processing
 6.1. format paramter for strnode
 6.2. strnode and catanode/dirnode
 7. catalog and src code
 7.1. create or update src code by design file
 7.2. create or syncronize back to design file by src code
 8. itemnode
 8.1 node type
 8.2 var2cata()
 8.3 item2var()
 9. conclusion



# 1.introduction
================
    catalog is a syntax of text file developed by my self. at first, i'm writing program module design draft by tab indented text, 
to express 'sub-' structure between two items. and i create source file dir accroding this text guide doc.
    i copy one source code file to create a new source code file, and modify module name of source file frequently. i have an idea 
that, the framework of source code file can be generated by the draft doc file.
    so, catalog file is borned.
    and catalog file also can be used for other purpose:

@ test code generation like source code generation.
@ menu description for displaying of program, neither console menu, nor gui 
  menu.
@ use it as a config file in soft pkg by config menu.

    usually, it is used for doc wrting, and generate other docs or source code.


# 2.example
===========

#
# 1. paramters for global catalog file
#
[param]

# public paramter define include
minc catalog.imi

node_seperater="."

# general syntax defination.
node_gen_fmt="@(rptchar ' ')<@{ITEM_VAR[0]}>.[@{ITEM_VAR[1]}].@{ITEM_VAR[2]}.\"@{ITEM_VAR[3]}\""
node_dispose_syntax="([ \t]+)<([0-9.<>])>\.[([a-zA-Z0-9_]+)]\."([a-zA-Z0-9-_ ]+)""

# normally, it is no need to set this variable. use node info instead.
dirnode_gen_fmt="@(rptchar ' ')<@{ITEM_VAR[0]}>.[@{ITEM_VAR[1]}].@{ITEM_VAR[2]}.\"@{ITEM_VAR[3]}\""
dirnode_dispose_syntax="([ \t]+)<([0-9.<>])>\.[([a-zA-Z0-9_]+)]\."([a-zA-Z0-9-_ ]+)""

# normally, it is no need to set this variable. use node info instead.
itemnode_gen_fmt="@(rptchar ' ')<@{ITEM_VAR[0]}>.[@{ITEM_VAR[1]}].@{ITEM_VAR[2]}.\"@{ITEM_VAR[3]}\""
itemnode_dispose_syntax="([ \t]+)<([0-9.<>])>\.[([a-zA-Z0-9_]+)]\."([a-zA-Z0-9-_ ]+)""

# it's defined by codegen
contnode_gen_fmt="@(rptchar ' ')<@{ITEM_VAR[0]}>.[@{ITEM_VAR[1]}].@{ITEM_VAR[2]}.\"@{ITEM_VAR[3]}\""
contnode_dispose_syntax="([ \t]+)<([0-9.<>])>\.[([a-zA-Z0-9_]+)]\."([a-zA-Z0-9-_ ]+)""


#
# 2. catalog for dir structure
#
[catalog-dir]
<1>.[dir].FirstModuleSet."first module set"
    <1>.[item].TestModule."program module for testing"
    # means it's catalog id is followed from sbove.
    # it's usefull when i copy text to other place.
    <->.[item].NextTestModule."the other test module"
<->.[dir].SecondModuleSet."second module set"
    <1>.[item].ThirdTestModule."the third test module"

#
# 3. catalog for item content
#
[catalog-content]
<->.[item].TestModule."program module for testing"
    <1>.[var].TestVar."test var for this module"
    <->.[func].TestFunc."test function for this module"
    
<->.[item].NextTestModule."the other test module"
    <1>.[var].TestVar2."test var2 for this module"
    <->.[func].TestFunc2."test function2 for this module"
    
<->.[item].ThirdTestModule."the third test module"
    <1>.[var].TestVar3."test var3 for this module"
    <->.[func].TestFunc3."test function3 for this module"

    
    there are three part of a catalog file.
@ paramter, used for catalog dispose. any paramter is setted by cmd line also can be setted in this section.
@ catalog-dir, it describe a dir structure for dir/file generating.
@ catalog-content, it is usually used for generate file content. if it is put on catalog-dir, the catalog information is not very clear. it likes a book, catalog-dir is catalog, and here is content.
    
    the id of item is '-'. it will be fill with correct id increased from lastest one.


# 3.concept
===========
         concept & words & short-name & short name combination.
         
[concept]
@ the feature of catalog: it include catalog, dst-dir, and filecont. and normally is used to generate files automatically.
@ catalog: it is a tree structured txt file, and is used to wrting note or setting paramter. it is consisted by catanode.
@ dst-dir: the things outputed on file system accrodding catalog data. it is consisted by dirnode and itemnode.
@ filecont: file content generated by catalog data and file templete. it is consisted by contnode.
@ translation: catalog is a src design file, and dst-dir is the output thing. generating operation between catalog and dst-dir, 
is translate operation. the higher level is catalog to dst-dir/filecont, the lower level is catanode to dirnode/itemnode/contnode.
|- catalog <=> varnode <=> dstdir/filecont
|- catanode <=> varnode <=> dirnode/itemnode/contnode(cata2dir/dir2cata/cata2item/item2cata, cata2cont/cont2cata)
    finally, the translate operation is between varnode and other node.
catanode/dirnode/itemnode/contnode <=> varnode(cata2var/var2cata, dir2var/var2dir/item2var/var2item, cont2var/var2cont)

@ catalog(cata):
# catanode(cnode): node in catalog. it is a sting.
# dircata: dir catalog string in catalog.
# itemcata: item catalog string in catalog.
# contentcata(contcata): content catalog string in catalog.

@ var: attribute variable.
# varnode(vnode): attr-var used to describe a node.
# varlist: it is also a attribute variable, that consisted by varnode.

@ outputnode(onode): it is the node entity that varnode generated.
# dirnode(dnode): dir cata in file system.
# itemnode(inode): item cata file in file system.
# contentnode(contnode): content cata data in item file.

@ node: a node is strnode + physical-feature. the expration method of a node, is the strnode. so, the translating operation
between varnode and other node, is also the translating operation between varnode and strnode. strsyntax.shlib implement this
feature.
@ field: the string consist of a strnode.
@ strnode: a formatted string consisted by some string data.
strnode <=> varnode(str2var/var2str)
@ varnode: it is an attr-var to describe a node. the attr content is the string data corresponding to a actual node.
@ dirnode: dir in dst-dir. it is consisted by dirnode * N + itemnode * N.
@ itemnode: an item is consisted by a set of file. it is consisted by strnode * N.
@ contnode: the output file is a language src file, contnode is one of the language feature in src code.
@ catanode: one line formatted string in catalog. it the general name of dircata/itemcata/contcata

@ dircata: it is a dir/file structure of catalog,
@ itemcata: it is the item node description.
@ contcata: it is the content node in a file.

@ var, variables that store data for one node line.
@ list, describe variables under a node, or list all node in catalog file.
@ varlist, 

@ dircata, dir desc node in catalog. generally, it is just named as catanode.
@ dirnode, one dir or one file on filesystem.
@ dirvar, a set of var to express one dir/file. generally, it is just named as varnode.
@ dirlist, a set of array, to record dir/file in dir without file content node, dirlist=dirvar*N. generally, it is just named 
as varlist.


# 4.attr-var
============
        attr-var is the short name of attribute variable.
        there no structured variable in shell environment. attr-var is used to orgnize variable like a structure, so that developers
can use the attr-var name as a paramter, it carried lots of variable information. 
        attr-var describe a node, and there are many node in catalog file or filesystem or file-content. put those attr-var translated
from strnode together as a integerated attr-var, it is called as 'varlist', it's the list of attr-var. the operation on catalog
or filesystem-dir or file-content, can be moved on varlist. it's the middle thing in translation.
        see the chapter of 'attr-var', and get the detail usage.


# 5.operation
=============
    the main function of catalog is generating files automatically. generally, files is program src code file, or testcase unit.
        catalog file is the source of codegen. it generate dir & files(item) on filesystem, and generated file content by templete.
        
             / dir & files(item)
catalog <=> |
             \ content

        uses function catalog2dstdir()/dstdir2catalog(). those two function is mapped to program paramter of "dst-dir generating 
or updating" and "generating or syncronize back to catalog".

        when catalog file is used to generate or update src-code, the translating step is like below.
catalog => dircata/itemcata => varnode => dir-varlist => varnode => dirnode/itemnode => dst-dir
                               =================================
           ===========================                   ===========================
=======---------------------------------------------------------------------------------=======
catalog => contcata => varnode => cont-varlist => varnode => contnode => filecont
                       ==================================
           ===================                    ===================
=======------------------------------------------------------------------=========

    when dir/files is used to generate or syncronize back to catalog file, the step is like below.
dst-dir => dirnode/itemnode => varnode => dir-varlist => varnode => dircata/itemcata => catalog
                               =================================
           ===========================                   ===========================
=======---------------------------------------------------------------------------------=======
filecont => contnode => varnode => cont-varlist => varnode => contcata => catalog
                         ==================================
             ===================                    ===================
=========------------------------------------------------------------------=======

        "-" connect two part of translation. use function dstdir2catalog()/catalog2dstdir()/filecont2catalog()/catalog2filecont().
        it's the interface for program running. it will invoke some 'foreach' function to trig node data translating.

    the operation in step is consisted by two part. and itemnode is the middle thing in those two step.
        one step is catalog structure processing. it is relatived to physical dir/file on filesystem. it's the same part of any file 
generating operation.
        the other step is content processing. different item file-type uses different templete file.

        catalog operation is equal to node operation. because node is the basical unit, either in catalog file, or in dst-dir on 
filesystem.
        
            / dircata  \      / dirvar   \       / dirnode   <=> dir on
                                                                                                                                 filesystem
catanode =>| itemcata   | <=> | itemvar   | <=> | itemnode   <=> dir/files on 
                                                                                                                                 filesystem
            \ contcata /      \ contvar  /       \ contnode  <=> content in 
                                                                                                                                 file
        
        dircata/itemcata/contcata in catalog file is nearly the same. so, combine them as catanode. it is also the same on 
dirvar/itemvar/contvar, and combine them as varnode. the process procedure is below.

catanode <=>           varnode      <=>    dirnode/itemnode/contnode
      cata2var()     var2dir()/var2item()/var2cont()
      var2cata()     dir2var()/item2var()/cont2var()

        use function :

@ cata2var()/var2cata(), 
@ dir2var()/var2dir()/item2var()/var2item(), 
@ cont2var()/var2cont().

    all those thing is node, and dirnode/itemnode/contnode is very similar with catanode, they are a string with some particular
feature. actually, the general processing procedure is string processing with varnode. i give it a name called strnode.
        dirnode = strnode + dir, itemnode = ( strnode + file ) * N.
        now, the traslation between varnode and other node, it looks like this:

strnode <=> varnode.

        use function str2var()/var2str().


# 6.node processing
===================
        node is the basic unit of catalog and dst-dir, strnode is the general part of them. so, every node operation with the 
corresponding feature, dir/file on filesystem, or string processing in file. and the general operation.

catanode <=> varnode <=> dirnode/itemnode/contnode
strnode <=> varnode.

        ignor the particular operation, we focus on translation between strnode and varnode. the function we need to care about is 
str2var()/var2str().
        those two function translat a formatted string, to a attribute variable. the acual processing procedure reference from chapter 
of 'strnode and catanode/dirnode'.

        contnode is different from dirnode and itemnode, it is used for templete feature. reference this feature from the chapter about
codegen.

        the node of '<catalog-bottom>' is used to exit from catalog file disposing. the whole catalog dispose is based on imi file
dispose. this tag break catalog dispose, and back to imi file dispose.
        it is used to process two stage of catalog content. put a tag at the end of dir catalog section, it trig a catalog process 
function, and generate dst-dir. and invoke file content function in content catalog section every item node.


# 6.1.format paramter for strnode
=================================
        in catalog file, catanode is a one-line-string with a format. and other thing like dirnode/itemnode/contnode is also a formatted
string.
        the purpose of catalog file is the note for code design, dirnode/itemnode is a normal file name string seperated by '.', and 
contnode is the grammar element in a program language. so, the string format is designed accrodding to it's using purpose.
        in a catalog file, we write doc for program module, and catagory them by dir structure. a catanode is a record in database, 
it is consisted by some data-field it needed. see the example above. greb a piece of txt as an example:

<->.[item].TestModule."program module for testing"
<cataid>.[node-type].name."desc"

        the format of a catanode is consisted by cataid/node-type/name/desc. function str2var() and var2str() is used to translate 
between them. attr-var include variable cataid/node-type/name/desc.
        it this format fixed? or how to describe this format?
        it defined some paramter in some imi file like below.

# catalog node string
[catanode]
attr node_fmt='<@{0}> [@{1}] @{2} "@{3}"'
attr var_rege="([a-zA-Z0-9_ ]*)"
#attr regexpr='<([a-zA-Z0-9_ ]*)> [([a-zA-Z0-9_ ]*)] ([a-zA-Z0-9_ ]*) "([a-zA-Z0-9_ ]*)"'
attr sepchar='.'
attr attr_wrap=( "none" "wrap1" "wrap2" "wrap3" "<" "<<" "<<<" "[" '\"" "[" )
attr attr_idx=( NID NTYPE NNAME NDESC )
attr nid_idx= 0

        string generate by attr-var is very easy, it invoke strfmt() to generate string by node_fmt attribute and attr-var.
        there are 3 type of method to dispose a strnode to attr-var.
@ using one char to seperate data-field, and give a wrap of data-field like "<>" or "[]". it is a easy way to implement string
dispose.
@ using reg-expr string to describe strnode format, and use =~ operator in shell with a reg-expr matching.
@ node_fmt is defined to generate strnode, and use this format to dispose strnode. the paramter var_rege is define for variable
in node_fmt. replace var_rege to variable, we get the reg-expr string like paramter 'regexpr'. the match result is stored in 
variable defined in node_fmt. it's the easist way to use strnode fmt, but cost a bit more cpu usage, but it is easy to use, and
can be defined smartfull.

        those three method is associated to var_rege/regexpr/sepchar. so, if the paramter is defined, using the method it takes.

        other side, the strnode format paramter for dirnode/itemnode/contnode is also defined like catanode. the actual implement
code of those tree method is ignored in this document, look at the src file in shlib.


# 6.2.strnode and catanode/dirnode
==================================

catalog => dircata/itemcata => varnode => dir-varlist => varnode => dirnode/itemnode => dst-dir
           ===========================                   ===========================
catalog => contcata => varnode => cont-varlist => varnode => contnode => filecont
           ===================                    ===================

dst-dir => dirnode/itemnode => varnode => dir-varlist => varnode => dircata/itemcata => catalog
           ===========================                   ===========================
filecont => contnode => varnode => cont-varlist => varnode => contcata => catalog
            ===================                    ===================

        catanode, dirnode, itemnode, is input or output node. and varnode is a media for translation between other node.
        in chapter 'operation', we absolute general node as a strnode, which is a formatted string, and use str2var()/var2str() for 
translation. in this chapter, we discuss the implementation of str2var()/var2str(). 

        translation between strnode and varnode:
+ use strfmt to generate string.
+ use seperated char to divide string into an array. uae idx to attr, store in corresponding attr var.
+ use regexpr, output matching string.
+ use node_fmt paramter that same as the one for strfmt. fill var regexpr string into node_fmt, it's the same as regexpr.


# 7.catalog and src code
========================
        the main purpose of catalog file is generating src code framework. there are several operations:
@ generate new src code framework by catalog file.
@ update changes on existing src code, which is generated by codegen.
@ generate new catalog file by src code dir.
@ syncronize src code back to catalog file.

        tihs chapter is discuss around those feature.


# 7.1.create or update src code by design file
==============================================
            / dir & files(item)
catalog => |
            \ content

catalog => dircata/itemcata => varnode => dir-varlist => varnode => dirnode/itemnode => dst-dir
=======---------------------------------------------------------------------------------=======
catalog => contcata => varnode => cont-varlist => varnode => contnode => filecont
=======------------------------------------------------------------------========

        in this chapter, we focus the point at translation between catalog and dst-dir/filecont. the function catalog2dstdir(), 
catalog2filecont() take this work as a interface for program feature implement. and the lower level function, translation between 
catanode and others, is introduced above.
        here we talk about the thing, what's the implementation in the function like dstdir2catalog().
        file content is implemented by temeplete feature in shlib, it uses varlist to generate src file content. we talk it in an other
chapter.
        
        there two type of method to generate dst-dir by catalog file.
@ ergodic the catalog file, and dispose catanode one by one in catalog file, and invoke translating function every catanode disposeed.
@ ergodic the catalog file, and dispose catanode to a varlist. ergodic varlist, and invoke translating function every varnode.

        it looks the same, and varlist is redundent. but think about the condition when the dst-dir is exist. the generating operation
is changed with update operation. in order to compactive with new create operatioin, we call this generating. it include new 
creatioin and exist update.
        there are also N method to process generating operation.
@ ergodic catalog, and dispose strnode to varlist. ergodic itemnode in dst-dir one by one without varlist generating, compare varnode with the one in catalog varlist.
+ node is the same, skip operation.
+ node is different, rename dirnode/itemnode by catalog varnode.
+ node is not exist in catalog varlist, move the dirnode/itemnode to trash.
        delete varnode in catalog varlist after comparation. at the end of dst-dir ergodic, ergodic catalog varlist again, and create 
dirnode/itemnode.
@ ergodic catalog & dst-dir, and dispose strnode to varlist. ergodic dst-dir varlist, compare varnode with the other one in 
catalog varlist.
+ node is the same, skip operation.
+ node is different, rename dirnode/itemnode by catalog varnode.
+ node is not exist in catalog varlist, move the dirnode/itemnode to trash.
        delete varnode in dst-dir varlist after comparation. at the end of varlist ergodic, ergodic dst-dir varlist again, and create 
new dirnode/itemnode.
@ ergodic catalog & dst-dir, and dispose strnode to varlist. ergodic catalog varlist, compare varnode with the other one in 
dst-dir varlist.
+ node is the same, skip operation.
+ node is different, rename dirnode/itemnode by catalog varnode.
+ node is not exist in dst-dir varlist, create dirnode/itemnode.
        delete varnode in dst-dir varlist after comparation. at the end of varlist ergodic, ergodic dst-dir varlist again, and move 
the dirnode/itemnode to trash.
@ ergodic catalog, and dispose strnode to varlist. ergodic current dir in dst-dir without varlist generating, compare varnode with the one in catalog varlist.
+ node is the same, skip operation.
+ node is different, rename dirnode/itemnode by catalog varnode.
+ node is not exist in catalog varlist, move the dirnode/itemnode to trash.
        delete varnode in catalog varlist after comparation. at the end of current dir ergodic, ergodic catalog varlist, and move 
the dirnode/itemnode to trash.
@ ergodic catalog, and dispose strnode to varlist. ergodic current dir in dst-dir with varlist. ergodic catalog varlist 
continously, compare catalog varnode with the one in current dir varlist.
+ node is the same, skip operation.
+ node is different, rename dirnode/itemnode by catalog varnode.
+ node is not exist in current dir varlist, create the dirnode/itemnode.
        delete varnode in current dir varlist after comparation. at the end of current dir ergodic, ergodic current dir varlist again, 
and move the dirnode/itemnode to trash.

        here, we use catalog varlist ergodic instead of catalog ergodic, for exist updating condition.
        and we can ergodic whole dst-dir varlist, or ergodic dst-dir one by one. itemnode can be consisted by many files. getting the 
itemnode varlist is based on current file listing. the itemnode list under a dir is generated at the same time. so, it can't ergodic 
itemnode just one by one actually. the first method is not the executable one.
        the second and third method generate whole dst-dir varlist. it cost more memory resource rather than the last one.
        
        itemnode is a particular thing, it can be consisted by many files. the node dispose procedure is discussed in later.
        catalog2filecont() output src code content by templete, reference from chapter about codegen, or templete.


# 7.2.create or syncronize back to design file by src code
==========================================================
            / dir & files(item)
catalog <= |
            \ content

dst-dir => dirnode/itemnode => varnode => dir-varlist => varnode => dircata/itemcata => catalog
           ===========================                   ===========================
filecont => contnode => varnode => cont-varlist => varnode => contcata => catalog
=========------------------------------------------------------------------=======

        the procedure is similar with design file to src code. we need to care about this thing:
@ itemnode list is generated together in a dir, not one by one.
@ dest catalog node is existing when generate node by dirnode/itemnode.
@ the sequence of catanode in catalog file, especially when the catalog file is existing.
@ some dst-dir node contains cataid, but the other one maybe not contained.
        
        so, the process procedure is :
@ ergodic catalog, and dispose strnode to varlist. ergodic current dir in dst-dir with varlist.
@ ergodic catalog varlist continously, because we want to keep the order of catanode as we can. so the default catanode generating
sequence is based on the original catalog varlist. 
@ compare catalog varnode with the one in current dir varlist, if there is a cataid in current dir varlist.
+ output catanode string by current dir varnode in varlist. unset the varnode in catalog varlist.
+ ergodic varnode in current dir of catalog varlist by current level cataid, and append catanode string by catalog varlist with 
'<->' cataid, and comment this row with '#'. it means it's the different catanode from dst-dir.
@ compare catalog varnode with the one in current dir varlist, if there is no cataid in current dir varlist.
+ if there is no cataid neither in catalog varlist, nor in dst-dir varlist, use the count number in current dir instead.
+ if the cataid is exist in catalog varlist, but not exist in dst-dir varlist, get the name of current catanode, get varnode in 
dst-dir varlist by this name string, then output catanode string by this varnode.
+ if the cataid is not exist in catalog varlist, but exist in dst-dir varlist, output catanode string by dst-dir varlist.

        delete varnode in catanode varlist after comparation. at the end of current dir ergodic, ergodic catanode varlist in current
dir by current level cataid. change cataid to '<->', and output this catanode string with '#' prefix.


# 8.itemnode
============
        every node is a formatted string with the corresponding physical-feature. eg: dirnode is a physical dir in file system, and 
a formatted dir name string.
        itemnode is a spacial node in catalog. it associated with several files. the function item2var()/var2item() is to be implemented.
it invoke str2var()/var2str() in lower level. the work different from other node processing, is that it should associate itemnode
with serveral strnode, then it invoke str2var()/var2str() as a normal node.

    <1>.[item].TestModule."program module for testing".[file:c-h-sh]
    <2>.[item].TestModule."program module for testing".[c_src]
    <3>.[item].TestModule."program module for testing".[test]

        it need a list of file name to be generated. and the file name is generated by 'file-type' in catanode.
        file-type string is consisted by two part:
@ type name
@ type file list. only 'file' has this paramter, and seperate type name with ':'


# 8.1.node type
===============
        type name is a tag string for a set of file with different surfix. the defination of this tag is in catalog file or imi 
paramter file it included.
        it is defined in strsyntax section of an imi file, or redefined in a catalog file.

[strsyntax]
# ÿһ¸öfextÀàÐÍÓжÔÓ¦µÄimi²ÎÊýÐÅÏ¢¡£
# ĬÈÏʹÓÃfileÀàÐÍ£¬¸ù¾Ý²ÎÊý´«µÝÀ©Õ¹Ãû×Ö·û´®£¬²¢×ª»»ÎªtypeÃû³ÆÁÐ±í¡£
#attr file::sfx='.c/.h/_test.c'
#attr file::typename='c/h/test_c'

# Áí°üº¬Ò»¸ösrcÀàÐÍ¡£ÓëfileÒ»Ñù¿ÉʹÓòÎÊýÁÐ±í¡£Êä³öÒ»¸ösrcÀàÐ͵Ätype£¬ÔÙ¸ù¾ÝÕâ¸ötype»ñÈ¡fextºÍ¶ÔÓ¦µÄtype

# fileÖ®ÍâµÄÆäËüÀàÐÍ£¬¸ù¾Ýsfx¶¨ÒåµÄÀ©Õ¹Ãû/surffixÁÐ±í£¬ÒÔ¼°¶ÔÓ¦µÄÀàÐÍÃû³ÆÁÐ±í¡£¸ù¾ÝÀàÐÍÃû³Æ£¬»ñÈ¡Ò»ÖÖÎļþÃûµÄ×Ö·û´®ÉèÖÃÐÅÏ¢¡£¸ù¾ÝÀàÐÍ
Ãû³Æ£¬Ê¹ÓöÔÓ¦µÄtmplÄ£°å¡£
# µ±typeÊôÐÔ䶨Òåʱ£¬Ê¹ÓÃsfxÊôÐÔµÄÖµ£¬²¢½«µÚÒ»¸ö.È¥µô£¬ÆäËü.Ìæ»»³É_¡£
attr src::sfx='.c/.h/_test.c'
attr src::typename='c/h/test_c'
attr shtest::sfx='.sh/.stdout'
attr shtest::typename='shtest/stdout'
attr module::sfx='.c/.h/.mdl/_test.c/.stdout'
attr module::typename='c/h/mdl/test_c/stdout'
# 

        src/test/module is defined as a type-name. it include attr of sfx(surfix) and type-tag. the attr of sfx is a list of file 
extension name seperated by '/', and type-tag is the corresponding type name used for file type defination attribute.

# shtest file name string
[shtest]
attr syntax::fmt='@{0}.@{2}.sh'
attr syntax::var_rege="([a-zA-Z0-9_ ]*)"
#attr syntax::regexpr=
attr syntax::sepchar='.'
attr syntax::attr_idx=( NID NNAME NFEXT )
attr syntax::nid_idx=0


# 8.2.var2item()
================
        strnode generate is a formatted string fill by varnode. the procedure of get_item_file_list() is :
        
varnode => file-type => strsyntax::<file-type>::typename => typename-array => <typename> define => strfmt() => strnode => itemnode

        get file file-type list of itemcata:
+ default file-type is file, use ext-nane in paramter list
+ src type, the same as file, use the pramter in 'src' attr var.
+ user defined type, include file ext-name and tmpl type string in paramter.


# 8.3.item2var()
================
        translating itemnode to varnode is more complex. there are two steps of this function:
@ get item name list in current dir.
@ translate itemnode to varnode by item name.

        there is not only one file associated with itemnode, so, itemnode can not be ergodiced one by one. use list_item_in_dir()
to get the item name list. the process procedure is like this:

strsyntax::inode::type =|
curr-dir => file-list  =|=> main item file list => varnode =|=> tmp-varlist => varnode |=> curr-dir-varlist
                        dir-list => str2var => varnode                 =|                          |=> ... => varnode => curr-dir-varlist

        it output a tmp-varlist, and generate dirnode if it is a dir object, and invoke item2var() if it is an item object.
        the procedure of itemnode translateing to varnode is like this:

       item-file-extname => <extname>::syntax::<attr> =| 
             ^                                         |
                     |--------------------------|              |
varnode => item-name => item-file-list =|=> item-file =|=> varnode-varlist => node_attr_combine() => varnode

        get attr of itemnode:
+ get catanode attr-var by 'name' of itemnode, use the type value to get ext-name list, 
+ get the item file list by get_item_file_list_in_dir(), and get the ext-name list.
+ compare two ext-name list if catanode type ext-name list exist.
+ or use ext-name to get file name syntax attr-var, and check file name by it.
+ if the file is not matching syntax get from  ext-name, use the surfix string after 'name', to get the ext-type attr-var. matching 
again, if matched, check if there are other file use the same ext-name. if no file found by this ext-name, delete this ext-name in 
list, insert surfix string instead.
+ matching ext-name list with the type defined in itemnode type list. no file matching, use file:<ext-name-list> instead.


# 9.conclusion
==============
        there are some thing we need to pay attension on it.
@ 2 stage processing, dir and content.
@ 2 direction of processing, catalog to src code, and opersite.
@ pay attension on itemnode:
+ the destination node is existing. ccomparesrc and dest varlist at the same time.
+ multi file, list item in a dir at the same time, and can't be ergodiced one by one. use curr-dir varlist instead of dst-dir 
varlist.
+ the cataid is existing in var node, use cataid from dst-dir/catanode/counter.
+ there is a sequence of catanode in catalog file. the sequnce is decided by cataid in dst-dir, or catanode sequence, or count 
number in curr-dir.
@ get file type list of itemcata
+ default type is file, use ext-nane in paramter list
+ src type, the same as file, use the pramter in 'src' attr var.
+ user defined type, include file ext-name and tmpl type string in paramter.
@ get file type attr of attr itemnode
+ get catanode attr-var by 'name' of itemnode, use the type value to get ext-name list, 
+ get the item file list, and get the ext-name list.
+ compare two ext-name list if catanode type ext-name list exist.
+ or use ext-name to get file name syntax attr-var, and check file name by it.
+ if the file is not matching syntax get from  ext-name, use the surfix string after 'name', to get the ext-type attr-var. matching 
again, if matched, check if there are other file use the same ext-name. if no file found by this ext-name, delete this ext-name in 
list, insert surfix string instead.
+ matching ext-name list with the type defined in itemnode type list. no file matching, use file:<ext-name-list> instead.
@ translation between strnode and varnode
+ use strfmt to generate string.
+ use seperated char to divide string into an array. uae idx to attr, store in corresponding attr var.
+ use regexpr, output matching string.
+ use node_fmt paramter that same as the one for strfmt. fill var regexpr string into node_fmt, it's the same as regexpr.


# Appendix. function list
=========================

# [attr.shlib]
# varlist_del()
# varlist_var_exist()
# varnode_in_list()

# varlist_foreach()


# [strsyntax.shlib]
# [strnode.shlib]
str2var()/var2str()


# [catadir.shlib]
# dir2var()/var2dir()
# item2var()/var2item()

# list_item_in_dir()
# node_attr_combine()
# get_item_file_list()
# get_item_file_list_in_dir()

# catadir_foreach()
# catadir_get_dir_varlist()


# [catalog.shlib]
# cata2var()/var2cata(),

# dstdir2catalog()/catalog2dstdir()
# filecont2catalog()/catalog2filecont()

# catalog_foreach()
# catalog_get_dir_varlist()
# catalog_get_cont_varlist()


# [c-lang.shlib]
# *cont2var()/*var2cont()

# content_foreach()
# content_get_cont_varlist()